/**
 *	\file
 *	\brief contains useful function to use throughout all the project
 *
 *	to Use effectively this library you <b>have</b> to call the function initLibrary()
 *
 * 	\date Jul 20, 2013
 * 	\author koldar
 */

#ifndef MAIN_TOOLS_H_
#define MAIN_TOOLS_H_

#include <stdio.h>

/**facet function to call in one instruction some other initialization functions
 *
 */
void initLibrary();

/**allocates new space in memory to holds a copy of the str passed as paramter.
 *
 * \pre
 *  \li str can't be NULL
 * \post
 *  \li a copy of str is stored in memory
 *
 * @param str
 * @return the pointer to the copy of the string
 */
char* initString(char* str);

/**allocates new space in memory to holds a copy of the str passed as parameter.
 * The string is C-like String Constant, like '"hello world"' or '"you are a \"robot\""'.
 * To store this string, the starting quote and the ending one must be removed.
 *
 * \dot
 * 	digraph {
 *		rankdir="LR";
 * 		n1 [label="\"hello World!\"" shape=none];
 * 		n2 [label="hello World!" shape=none];
 *
 * 		n1 -> n2;
 * 	}
 * \enddot
 *
 * \pre
 *  \li str is not NULL
 *  \li str begins with quote (")
 *  \li str ends with quote (")
 *  \li other inner quotes are escaped with backslash (\")
 * \post
 *  \li a string is allocated without the beginning quote and the ending one
 *  \li memory must be freed manually
 *
 * @param str the string c-like to malloc
 * @return a pointer to string
 */
char* initCString(char* str);

/**Free an already allocated string generated by:
 * \li initCString();
 * \li initString();
 *
 * \pre
 *  \li str is <b>not</b> null;
 *
 * @param str the string to be deallocated
 */
void freeString(char* str);

/**prints in the stream specified some tab characters
 *
 * \pre
 *  \li tabsnumber is greater or equal than 0
 * \post
 *  \li in f are printed tabsnumber '\t' characters
 *
 * @param f the file to change
 * @param tabsnumber the number of tabs to be printed on the file
 */
void printTabs(FILE* f,int tabsnumber);

#endif /* MAIN_TOOLS_H_ */
